Create Agent #

本文档中引用的文件

目录 #

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论

简介 #

prebuilt.CreateAgent 是 LangGraphGo 框架中的一个核心工厂函数，专门用于基于函数式选项模式（Functional Options Pattern）构建灵活的智能代理。该函数简化了 ReAct 模式代理的创建过程，提供了比基础 CreateReactAgent 更强大和可扩展的功能集。

主要特性 #

项目结构 #

graph TD
A[prebuilt/] --> B[create_agent.go]
A --> C[react_agent.go]
A --> D[tool_executor.go]
E[examples/] --> F[create_agent/]
E --> G[react_agent/]
H[graph/] --> I[state_graph.go]
B --> J[CreateAgent函数]
B --> K[CreateAgentOptions结构体]
B --> L[函数式选项]
F --> M[main.go示例]
F --> N[README文档]
C --> O[CreateReactAgent函数]
D --> P[ToolExecutor结构体]
I --> Q[StateGraph架构]

图表来源

章节来源

核心组件 #

CreateAgentOptions 结构体 #

CreateAgentOptions 是 CreateAgent 函数的配置选项容器，包含以下关键字段：

字段名 类型 描述
SystemMessage string 预设的系统提示消息，定义代理行为
StateModifier func([]llms.MessageContent) []llms.MessageContent 状态修改器函数，用于修改消息历史
Checkpointer graph.CheckpointStore 检查点存储接口，用于状态持久化

函数式选项模式 #

该函数采用经典的 Go 函数式选项模式，提供以下配置函数：

章节来源

架构概览 #

CreateAgent 函数构建了一个完整的状态图代理系统，其架构如下：

graph TB
subgraph "CreateAgent 架构"
A[初始化 LLM] --> B[创建工具执行器]
B --> C[构建状态图]
C --> D[定义状态模式]
D --> E[添加代理节点]
E --> F[添加工具节点]
F --> G[定义边连接]
G --> H[编译图]
subgraph "代理节点逻辑"
E1[接收消息] --> E2[转换工具定义]
E2 --> E3[应用系统消息]
E3 --> E4[应用状态修改器]
E4 --> E5[调用 LLM]
E5 --> E6[处理工具调用]
E6 --> E7[返回 AI 响应]
end
subgraph "工具节点逻辑"
F1[解析最后消息] --> F2[提取工具调用]
F2 --> F3[执行工具]
F3 --> F4[创建工具响应]
F4 --> F5[返回工具消息]
end
E --> E1
F --> F1
end

图表来源

详细组件分析 #

CreateAgent 函数实现 #

初始化阶段 #

sequenceDiagram
participant Client as 客户端
participant Factory as CreateAgent
participant Options as CreateAgentOptions
participant Executor as ToolExecutor
Client->>Factory : CreateAgent(model, tools, opts...)
Factory->>Options : 创建默认选项
Factory->>Options : 应用所有选项
Factory->>Executor : NewToolExecutor(tools)
Factory->>Factory : 创建 StateGraph
Factory->>Factory : 设置状态模式

图表来源

代理节点实现 #

代理节点是整个系统的核心，负责：

  1. 消息验证: 确保状态格式正确
  2. 工具定义转换: 将工具列表转换为 LLM 可识别的格式
  3. 系统消息处理: 在消息历史前添加系统提示
  4. 状态修改器应用: 执行自定义的消息处理逻辑
  5. LLM 调用: 发送处理后的消息并获取响应
  6. 响应处理: 解析 LLM 输出，包括文本内容和工具调用
flowchart TD
Start([代理节点开始]) --> ValidateState["验证状态类型"]
ValidateState --> ExtractMessages["提取消息列表"]
ExtractMessages --> ConvertTools["转换工具定义"]
ConvertTools --> AddSystemMsg{"是否有系统消息?"}
AddSystemMsg --> |是| PrependSystem["前置系统消息"]
AddSystemMsg --> |否| ApplyModifier["应用状态修改器"]
PrependSystem --> ApplyModifier
ApplyModifier --> CallLLM["调用 LLM 模型"]
CallLLM --> ProcessResponse["处理 LLM 响应"]
ProcessResponse --> HasToolCalls{"有工具调用?"}
HasToolCalls --> |是| HandleToolCalls["处理工具调用"]
HasToolCalls --> |否| CreateAIMessage["创建 AI 消息"]
HandleToolCalls --> CreateAIMessage
CreateAIMessage --> ReturnResult["返回结果"]
ReturnResult --> End([结束])

图表来源

工具节点实现 #

工具节点负责处理代理发出的工具调用：

sequenceDiagram
participant Agent as 代理节点
participant ToolNode as 工具节点
participant Executor as ToolExecutor
participant Tool as 工具实例
Agent->>ToolNode : 发送工具调用消息
ToolNode->>ToolNode : 解析最后消息
ToolNode->>ToolNode : 提取工具调用部分
ToolNode->>ToolNode : 解析参数
ToolNode->>Executor : Execute(invocation)
Executor->>Tool : Call(ctx, input)
Tool-->>Executor : 返回结果
Executor-->>ToolNode : 返回执行结果
ToolNode->>ToolNode : 创建工具响应消息
ToolNode-->>Agent : 返回工具消息

图表来源

条件路由逻辑 #

系统使用条件边来决定执行流程：

flowchart TD
AgentNode[代理节点] --> CheckToolCalls["检查最后消息中的工具调用"]
CheckToolCalls --> HasToolCalls{"是否有工具调用?"}
HasToolCalls --> |是| ToolsNode["工具节点"]
HasToolCalls --> |否| EndNode["结束节点"]
ToolsNode --> AgentNode

图表来源

章节来源

函数式选项实现机制 #

WithSystemMessage 实现 #

系统消息选项通过闭包捕获配置值：

classDiagram
class CreateAgentOption {
<<function>>
+Apply(CreateAgentOptions)
}
class CreateAgentOptions {
+string SystemMessage
+func StateModifier
+CheckpointStore Checkpointer
}
CreateAgentOption --> CreateAgentOptions : 配置

图表来源

WithStateModifier 实现 #

状态修改器允许开发者在消息发送给 LLM 前进行自定义处理：

sequenceDiagram
participant Agent as 代理
participant Modifier as 状态修改器
participant LLM as LLM模型
Agent->>Modifier : 调用 StateModifier(messages)
Modifier->>Modifier : 自定义处理逻辑
Modifier-->>Agent : 返回修改后的消息
Agent->>LLM : 发送处理后的消息

图表来源

章节来源

ToolExecutor 组件 #

工具执行器是代理系统的重要组成部分，负责：

classDiagram
class ToolExecutor {
+map[string]tools.Tool tools
+Execute(ctx, invocation) string, error
+ExecuteMany(ctx, invocations) []string, error
+ToolNode(ctx, state) interface, error
}
class ToolInvocation {
+string Tool
+string ToolInput
}
class Tool {
<<interface>>
+Name() string
+Description() string
+Call(ctx, input) string, error
}
ToolExecutor --> Tool : 管理
ToolExecutor --> ToolInvocation : 处理

图表来源

章节来源

依赖关系分析 #

核心依赖关系 #

graph TD
A[CreateAgent] --> B[StateGraph]
A --> C[ToolExecutor]
A --> D[llms.Model]
A --> E[tools.Tool]
B --> F[StateRunnable]
B --> G[StateSchema]
B --> H[Node]
C --> I[ToolInvocation]
C --> E
A --> J[CreateAgentOptions]
J --> K[WithSystemMessage]
J --> L[WithStateModifier]
J --> M[WithCheckpointer]
subgraph "外部依赖"
D --> N[langchaingo/llms]
E --> O[langchaingo/tools]
F --> P[graph package]
end

图表来源

测试依赖关系 #

graph TD
A[CreateAgentTest] --> B[MockLLM]
A --> C[MockTool]
A --> D[MockLLMWithInputCapture]
B --> E[GenerateContent]
C --> F[Name/Description/Call]
D --> G[CapturedMessages]
A --> H[CreateAgent]
H --> I[StateRunnable]

图表来源

章节来源

性能考虑 #

并发处理 #

内存管理 #

扩展性 #

故障排除指南 #

常见问题及解决方案 #

1. 系统消息未生效 #

问题: 设置了 WithSystemMessage 但 LLM 未使用

原因: 状态修改器可能移除了系统消息

解决方案: 检查状态修改器逻辑，确保保留系统消息

2. 工具调用失败 #

问题: 代理尝试调用工具但执行失败

诊断步骤:

3. 状态类型错误 #

问题: 运行时出现类型断言错误

解决方案: 确保输入状态符合预期格式：

initialState := map[string]interface{}{
    "messages": []llms.MessageContent{
        llms.TextParts(llms.ChatMessageTypeHuman, "用户消息"),
    },
}

章节来源

结论 #

prebuilt.CreateAgent 函数代表了 LangGraphGo 框架中智能代理构建的最佳实践。通过采用函数式选项模式，它提供了：

主要优势 #

  1. 简洁的 API: 清晰的配置方式，易于理解和使用
  2. 高度可扩展: 支持自定义系统消息和状态处理逻辑
  3. 内置智能: 自动处理工具调用和条件路由
  4. 类型安全: 强类型接口确保运行时稳定性
  5. 测试友好: 清晰的依赖关系便于单元测试

使用建议 #

未来发展方向 #

通过深入理解 CreateAgent 的实现原理和最佳实践，开发者可以构建出功能强大、可维护性强的智能代理系统，为用户提供卓越的交互体验。